Description

Implements an interactive N-Z (Neutron-Proton) diagram, also known as a Segré Chart, for visualizing nuclear stability patterns across 321 nuclides from the database. This educational tool helps users understand nuclear stability, magic numbers, and decay patterns in the context of LENR research.

Type of Change

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• Performance improvement
• Code refactoring (no functional changes)
• Documentation update
• Dependency update
• Other (please describe):

Related Issues

Motivation and Context

The Segré Chart (N-Z diagram) is a fundamental tool in nuclear physics for understanding nuclear stability. It provides visual context for:

• Which nuclides are stable vs unstable
• The "valley of stability" where stable nuclides cluster
• Magic numbers (2, 8, 20, 28, 50, 82, 126) representing closed nuclear shells
• Decay modes based on position relative to the N=Z line

This visualization helps LENR Academy users explore nuclear transmutation pathways in the context of established nuclear physics theory, making it easier to identify patterns and understand why certain reactions are favorable.

Changes Made

New Components:

• src/components/IsotopeChart.tsx - SVG-based interactive scatter plot (390 lines)

  • Pan and zoom with mouse/touch support
  • Hover tooltips showing nuclide details
  • Click navigation to element data pages
  • Color-coded by stability status
  • Toggleable overlays (valley, magic numbers)

• src/pages/IsotopeChart.tsx - Page wrapper with controls (201 lines)

  • Toggle switches for valley and magic numbers
  • Legend display control
  • Chart statistics

New Services:

• src/services/isotopeChartService.ts - Data fetching and processing (215 lines)
  • Queries NuclidesPlus table
  • Calculates neutron count (N = A - Z)
  • Categorizes by stability status

Routing:

• Added /isotope-chart route in src/App.tsx
• Added navigation link in src/components/Layout.tsx

Types:

• Added IsotopeData interface
• Added MagicNumber type
• Added StabilityStatus type

Testing:

• e2e/tests/isotope-chart.spec.ts - E2E tests for interactions (185 lines)
• Added navigation test in e2e/tests/navigation.spec.ts

Testing

Test Environment

• Browser(s): Chrome 120, Firefox 121
• OS: Linux, macOS
• Device: Desktop / Mobile

Test Cases

• Manual testing completed
• Tested on multiple browsers
• Tested on mobile devices (needs testing)
• Tested with slow/metered connections (uses cached database)
• Tested database loading and caching

Test Results

• ✅ Chart renders with 321 nuclides correctly positioned
• ✅ Hover tooltips display accurate nuclide information
• ✅ Click navigation to element data pages works
• ✅ Valley of stability toggle shows/hides overlay
• ✅ Magic numbers toggle shows/hides markers
• ✅ Pan and zoom functionality works smoothly
• ✅ Legend displays correctly with color coding
• ✅ E2E tests pass for all interactions

Database Impact

• No database changes
• New queries added (reads from existing NuclidesPlus table)
• Query optimization/changes
• Database schema understanding updated
• Requires new database version or migration

Query Details:

SELECT Z, A, E, LHL, SUS FROM NuclidesPlus ORDER BY Z, A

This is a simple read-only query on an existing table.

Performance Impact

• No performance impact expected
• Performance improvement (describe below)
• Potential performance regression (describe mitigation below)

Performance notes:

The query retrieves ~321 nuclides (very small dataset). SVG rendering is efficient for this number of elements. Pan/zoom uses CSS transforms (GPU-accelerated). No performance concerns.

UI/UX Changes

Screenshots

Desktop View:

Mobile View:
(Needs testing and screenshots)

Responsive Design

• Tested on desktop (1920x1080+)
• Tested on tablet (768px-1024px) - needs testing
• Tested on mobile (320px-767px) - needs testing
• Dark mode tested
• Light mode tested

Documentation

• Code is self-documenting with clear variable/function names
• Added/updated code comments for complex logic
• Updated CLAUDE.md (should document this feature)
• Updated README.md (not necessary, UI is self-explanatory)
• Added JSDoc comments for new functions/components

Code Quality

• Code follows the existing style and patterns
• TypeScript types are properly defined (no any unless necessary)
• No console.log or debugging code left in
• Removed unused imports and variables
• npm run lint passes without errors (needs verification)
• npm run build completes successfully (needs verification)

Deployment Checklist

• Tested in production build (npm run build && npm run preview)
• No hardcoded development URLs or API keys
• Asset paths are correct for CloudFront/S3 deployment
• Analytics/privacy features work correctly

Breaking Changes

Does this PR introduce breaking changes? No

Rollback Plan

• Simple git revert
• Requires database rollback (describe):
• Requires cache clearing (localStorage/IndexedDB)

This is a purely additive feature. A simple git revert removes the new route and navigation link without affecting existing functionality.

Additional Notes

Educational Value:

• Helps users understand nuclear stability theory
• Provides visual context for transmutation pathways
• Shows relationship between N, Z, and stability
• Highlights importance of magic numbers in nuclear physics

Future Enhancements:

• Add filtering by stability status
• Add decay mode visualization
• Link directly to reactions involving each nuclide
• Add export to image functionality